<?
/*
 * emarket - a website to create your own online-shop.  
 * Copyright (C) 2009  Frédéric Delorme
 *
 * This file is part of emarket.
 *
 * emarket is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * emarket is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with emarket.  If not, see <http://www.gnu.org/licenses/>.
 *
 * To contact me: frederic.delorme@gmail.com
 * to see some information on te project : http://code.google.col/p/os-emarket/
 *
 */
/**
 * Abstract class to guide any persistence data class.
 * @author frederic delorme
 *
 */
abstract class DataPersistence extends Data{
	/**
	 * pre-load of data parameters.
	 */
	abstract protected function loadParameters();
	
	/**
	 * Retrieve all entities of type $type.
	 * @param $type
	 * @return array() of entities
	 */
	abstract public function getEntities($type="");

	/**
	 * return the entity of $type with $id.
	 * @param $type string type of the entity.
	 * @param $id integer or string identifier of the entity
	 * @return array() containing the Record. 
	 */
	abstract public function getEntity($type="",$id="");

	/**
	 * return the entity of $type with $id with all (or specified) $associates entities.
	 * @param $type string type of the entity.
	 * @param $id integer or string identifier of the entity
	 * @param $associates array of linked entities types, to retrieve linked data. By default, all entity type will be retrieved.
	 * @return array() containing the Record. 
	 */
	abstract public function getEntityAssociates($type="",$id="", $associates="all");
	
	
	/**
	 * Convert the description type (from model.ini) into the corresponding database field type.
	 * @param $type in the model.ini file.
	 * @return String the corresponding type into the MySql database.
	 */
	abstract public function convertFieldType($fieldtype="",$size=0,$options="");	
	
	/**
	 * <p>Retrieve entities of $type with the following list of clause.</p>
	 * @param $type <p>entity type to be retrieved.</p>
	 * @param $where <p>the where clause id an array of criteria. All criteria are assembled in a AND operator.
	 * Each criteria contains 3 values: <pre>field</pre>, <pre>comparator</pre> and <pre>value</pre>:</p>
	 * <dl>
	 * 	<dt>field</dt>
	 * 	<dd>the name of the field where to apply clause.</dd>
	 * 	<dt>comparator</dt>
	 * 	<dd>any validated comparator for your database implementation ('=','>','<','like','!=', etc...)</dd>
	 * 	<dt>value</dt>
	 * 	<dd>The value to be compared.</dd>
	 * </ul>
	 * <p>example: </p>
	 * <pre>
	 * $where=array(
	 *   array('field'=>"field1",'comparator'=>">",'value'=>"120"),
	 *   array('field'=>"field2",'comparator'=>"<",'value'=>"120"),
	 *   array('field'=>"field3",'comparator'=>"=",'value'=>"120"),
	 *   array('field'=>"field4",'comparator'=>"!=",'value'=>"120"),
	 *   </pre>
	 * @return array() of data.
	 */
	abstract public function queryEntities($type="",$where=array());
	
	/**
	 * Retrieve entities of $type with the following list of where clause and 
	 * sort them following the rules $sortorder.
	 * @see IData::queryEntities($type,$where)
	 * @param $type
	 * @param $where
	 * @param $sortorder <p>Added to the capabilities of the where clause, 
	 * this method add the sort capability. The usage is near the $where usage:</p>
	 * <p>Each sort order array must contains 2 values:</p>
	 * <dl>
	 * 	<dt>field</dt>
	 * 	<dl>The field where the sort must be applied.</dl>
	 * 	<dt>direction</dt>
	 * 	<dl>Can be <pre>ASC</pre> for ascending sort of <pre>DESC</pre> for descending sort.</dl>
	 * </dl>
	 * <p>example:</p>
	 * <pre>
	 * $sortorder=
	 * 	array(
	 * 		array('field'=>"created_at",'direction'=>"ASC")),
	 * 		array('field'=>"title",'direction'=>"DESC"))
	 * 	)
	 * </pre>
	 * <p>In the previous sample, the request will sort data according to the 
	 * 	<ul>
	 * 		<li><pre>created_at</pre> (Date) in an ascending order,</li>
	 * 		<li><pre>title</pre> (String) in a descending order.</li>
	 * 	</ul>
	 * </p>
	 * @return array() of data.
	 */
	abstract public function querySortedEntities($type="",$where=array(),$sortorder=array());
	
	/**
	 * create an entity of $type with the values from the $entity array.
	 * @param $type
	 * @param $entity
	 */
	abstract public function createEntity($type="",$entity=array());

	/**
	 * update an entity of $type with the values from the $entity array.
	 * @param $type
	 * @param $entity
	 */
	abstract public function updateEntity($type="",$entity=array());
	
	/**
	 * delete an entity of $type with the values from the $entity array.
	 * @param $type
	 * @param $entity
	 */
	abstract public function deleteEntity($type="",$entity=array());
	
	/**
	 * Parameter getter.
	 * @param $group
	 * @param $key
	 */
	abstract public function getParam($group="",$key="");
	
	/**
	 * Group of parameters getter.
	 * @param $group
	 * @return unknown_type
	 */
	abstract public function getGroupParam($group="");
	
	/**
	 * create data $entity into the $type entity.
	 * @param $type
	 * @param $entity
	 */
	abstract protected function create($type="", $entity=array());

	/**
	 * update data $entity into the $type entity.
	 * @param $type
	 * @param $entity
	 */
	abstract protected function update($type="", $entity=array());
	
	/**
	 * delete data $entity into the $type entity.
	 * @param $type
	 * @param $entity
	 */
	abstract protected function delete($type="", $entity=array());
	
	/**
	 * generate the pagination statement for the datapersistence implmentation.
	 * @param String $limit
	 * @return String limit for the implemented persistence.
	 */
	abstract protected function getPagination($limit="");
	
}
?>